@sec-ant/zxing-wasm

@sec-ant/zxing-wasm

An ES module wrapper of zxing-wasm-build. Read or write barcodes in your browser!

Build

git clone https://github.com/Sec-ant/zxing-wasm
cd zxing-wasm
npm i
npm run fetch
npm run build

Install

npm i @sec-ant/zxing-wasm

Usage

This package exports 3 subpaths: full, reader and writer. You can choose whichever fits your needs. If you use TypeScript, you should set moduleResolution to bundler, node16 or nodenext in your tsconfig.json file to properly resolve the exported module.

@sec-ant/zxing-wasm or @sec-ant/zxing-wasm/full

These 2 subpaths include functions to both read and write barcodes. The wasm binary size is ~1.26 MB.

import {
  readBarcodesFromImageFile,
  readBarcodesFromImageData,
  writeBarcodeToImageFile,
} from "@sec-ant/zxing-wasm";

or

import {
  readBarcodesFromImageFile,
  readBarcodesFromImageData,
  writeBarcodeToImageFile,
} from "@sec-ant/zxing-wasm/full";

@sec-ant/zxing-wasm/reader

This subpath only includes functions to read barcodes. The wasm binary size is ~976 KB.

import {
  readBarcodesFromImageFile,
  readBarcodesFromImageData,
} from "@sec-ant/zxing-wasm/reader";

@sec-ant/zxing-wasm/writer

This subpath only includes functions to write barcodes. The wasm binary size is ~383 KB.

import { writeBarcodeToImageFile } from "@sec-ant/zxing-wasm/writer";

readBarcodesFromImageFile and readBarcodesFromImageData

These 2 functions are for reading barcodes.

readBarcodesFromImageFile accepts an image Blob or an image File as the first input. They're encoded images, e.g. .png .jpg files.

readBarcodesFromImageData accepts an ImageData as the first input. They're raw pixels that usually acquired from <canvas> or related APIs.

Both of these 2 functions accepts the same second input: ZXingReadOptions:

interface ZXingReadOptions {
  /* Try harder to find barcodes, default = true */
  tryHarder?: boolean;
  /* An array of barcode formats to detect, default = [] (indicates any format) */
  formats?: readonly ZXingReadInputBarcodeFormat[];
  /* Upper limit of the number of barcodes to be detected, default = 255 (max) */
  maxSymbols?: number;
}

The allowed barcode formats to read are:

type ZXingReadInputBarcodeFormat =
  | "Aztec"
  | "Codabar"
  | "Code128"
  | "Code39"
  | "Code93"
  | "DataBar"
  | "DataBarExpanded"
  | "DataMatrix"
  | "EAN-13"
  | "EAN-8"
  | "ITF"
  | "Linear-Codes"
  | "Matrix-Codes"
  | "MaxiCode"
  | "MicroQRCode"
  | "PDF417"
  | "QRCode"
  | "UPC-A"
  | "UPC-E";

The return result of these 2 functions is a Promise of an array of ZXingReadOutputs:

interface ZXingReadOutput {
  /* detected barcode format */
  format: ZXingReadOutputBarcodeFormat;
  /* detected barcode text */
  text: string;
  /* detected barcode raw bytes */
  bytes: Uint8Array;
  /* error message (if any) */
  error: string;
  /* detected barcode position:
    {
      bottomLeft:  { x, y },
      bottomRight: { x, y },
      topLeft:     { x, y },
      topLeft:     { x, y }
    }
  */
  position: ZXingPosition;
  /* symbology identifier: https://github.com/zxing-cpp/zxing-cpp/blob/1bb03a85ef9846076fc5068b05646454f7fe6f6f/core/src/Content.h#L24 */
  symbologyIdentifier: string;
  /* error correction code level: L M Q H */
  eccLevel: ZXingReadOutputECCLevel;
  /* QRCode / DataMatrix / Aztec version or size */
  version: string;
  /* orientation of barcode in degree */
  orientation: number;
  /* is the symbol mirrored (currently only supported by QRCode and DataMatrix) */
  isMirrored: boolean;
  /* is the symbol inverted / has reveresed reflectance */
  isInverted: boolean;
}

e.g.

import {
  readBarcodesFromImageFile,
  readBarcodesFromImageData,
  ZXingReadOptions,
} from "@sec-ant/zxing-wasm/reader";

const zxingReadOptions: ZXingReadOptions = {
  tryHarder: true,
  formats: ["QRCode"],
  maxSymbols: 1,
};

/**
 * Read from image file/blob
 */
const imageFile = await fetch(
  "https://api.qrserver.com/v1/create-qr-code/?size=150x150&data=Hello%20world!",
).then((resp) => resp.blob());

const imageFileReadOutputs = await readBarcodesFromImageFile(
  imageFile,
  zxingReadOptions,
);

console.log(imageFileReadOutputs[0].text); // Hello world!

/**
 * Read from image data
 */
const imageData = await createImageBitmap(imageFile).then((imageBitmap) => {
  const { width, height } = imageBitmap;
  const context = new OffscreenCanvas(width, height).getContext(
    "2d",
  ) as OffscreenCanvasRenderingContext2D;
  context.drawImage(imageBitmap, 0, 0, width, height);
  return context.getImageData(0, 0, width, height);
});

const imageDataReadOutputs = await readBarcodesFromImageData(
  imageData,
  zxingReadOptions,
);

console.log(imageDataReadOutputs[0].text); // Hello world!

writeBarcodeToImageFile

There is only 1 function to write barcodes. The first argument of this function is a text string to be encoded and the second argument is a ZXingWriteOptions:

interface ZXingWriteOptions {
  /* barcode format to write
     "DataBar", "DataBarExpanded", "MaxiCode" and "MicroQRCode" are currently not supported
     default = "QRCode" */
  format?: ZXingWriteInputBarcodeFormat;
  /* encoding charset, default = "UTF-8" */
  charset?: ZXingCharacterSet;
  /* barcode margin, default = 10 */
  quietZone?: number;
  /* barcode width, default = 200 */
  width?: number;
  /* barcode height, default = 200 */
  height?: number;
  /* (E)rror (C)orrection (C)apability level, -1 ~ 8, default = -1 (default) */
  eccLevel?: ZXingWriteInputECCLevel;
}

The return result of this function is a Promise of ZXingWriteOutput:

interface ZXingWriteOutput {
  /* a png image blob, or null */
  image: Blob | null;
  /* the error reason if image is null */
  error: string;
}

e.g.

import { writeBarcodeToImageFile } from "@sec-ant/zxing-wasm/writer";

const writeOutput = await writeBarcodeToImageFile("Hello world!", {
  format: "QRCode",
  charset: "UTF-8",
  quietZone: 5,
  width: 150,
  height: 150,
  eccLevel: 2,
});

console.log(writeOutput.image);

Notes

When using this package, the wasm binary needs to be served along with the JS glue code. In order to provide a smooth dev experience, the wasm binary serve path is automatically assigned the jsDelivr CDN url upon build.

If you would like to change the serve path (to one of your local network hosts or other CDNs), please use setZXingModuleOverrides to override the locateFile function in advance. locateFile is one of the Emscripten Module attribute hooks that can affect the code execution of the Module object during its lifecycles.

import {
  setZXingModuleOverrides,
  writeBarcodeToImageFile,
} from "@sec-ant/zxing-wasm";

// override the locateFile function
setZXingModuleOverrides({
  locateFile: (path, prefix) => {
    if (path.endsWith(".wasm")) {
      return `https://esm.sh/@sec-ant/zxing-wasm/dist/full/${path}`;
    }
    return prefix + path;
  },
});

// call read or write functions afterwards
const writeOutput = await writeBarcodeToImageFile("Hello world!");

The wasm binary won't be fetched or instantiated unless a read or write function is firstly called, and will only be instantiated once given the same module overrides. So there'll be a cold start in the first function call (or several calls if they appear in a very short period). If you want to manually trigger the download and instantiation of the wasm binary prior to any read or write functions, you can use getZXingModule. This function will also return a Promise that resolves to a ZXingModule.

import { getZXingModule } from "@sec-ant/zxing-wasm";

/**
 * This function will trigger the download and
 * instantiation of the wasm binary immediately
 */
const zxingModulePromise1 = getZXingModule();

const zxingModulePromise2 = getZXingModule();

console.log(zxingModulePromise1 === zxingModulePromise2); // true

getZXingModule can also optionally accept a ZXingModuleOverrides argument.

import { getZXingModule } from "@sec-ant/zxing-wasm";

getZXingModule({
  locateFile: (path, prefix) => {
    if (path.endsWith(".wasm")) {
      return `https://esm.sh/@sec-ant/zxing-wasm/dist/full/${path}`;
    }
    return prefix + path;
  },
});

License

MIT